How Do I Reference Images in My HTML Output Instead of Embedding in Java Engine?

When outputting to HTML, users can embed images as Base64-encoded data via an Import Tag or reference images by file locations pointing to the source. This article explains how to explicitly select either output method.

Default Behavior

The template used in all the examples below contains an Import Tag that imports an image from a URL.

The following code snippet shows our default behavior:

File fileReport = new File("out/report_default.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);
            
// Nothing specified yet
         
report.processSetup();
          
DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));
            
report.processData(datasource, "images");
            
report.processComplete();
template.close();
reportStream.close();    

This code creates the following HTML output. Images default to being embedded inside the HTML as Base64-encoded images:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en">
<style type="text/css">
p {
font-family:Calibri;
font-size:11.0pt;
color:#000000;
margin-top:0.0pt;
margin-bottom:8.0pt;
line-height:1.08;
margin-right:0.0pt;
border:0 none;
text-align:left;
text-indent:0.0pt;
}
IMG.centered{
    display: block;
    margin-left: auto;
    margin-right: auto
}IMG.right{
    float:right;
}IMG.left{
    float:left;
}
#container {
    width:624px;
    margin:0px auto;
}
</style>
</head>
<body><div id="container">
<p><br><img src="data:image/png;base64,/9j[...]42Q==" width="1024" height="768" /><br></p>
</div></body>
</html>

The same default output can be achieved by explicitly specifying embedding using the setEmbedImages method:

File fileReport = new File("out/report_true.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);

// Explicitly specify to embed images in output
report.setEmbedImages(true);

report.processSetup();

DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));

report.processData(datasource, "images");

report.processComplete();
template.close();
reportStream.close();

Referencing Image Locations in HTML Output

Alternatively, specify a location for the images to be saved as output is generated, and then reference these image locations in the HTML. Use two methods:

1. ProcessHtmlAPI.setImagePath(String s, String s2, String s3): specify the location to save images, the relative location from the HTML output to reference images, and the prefix to use for saved images. Read more here.
2. ProcessHtmlAPI.setEmbedImages(boolean b): set to false to use the specified image paths to save and reference images. Read more here.

The final code looks like this:

File fileReport = new File("out/report_false.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);

// Specify to use file reference instead of embedding images.
// Save images to the relative path "out/images"
// Since the HTML output is to the relative path "out" the relative image location to the HTML file is just "images"
// Prefix the saved image names with "outputImage"
report.setImagePath("out/images", "images", "outputImage");
// Explicitly override default functionality
report.setEmbedImages(false);

report.processSetup();

DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));

report.processData(datasource, "images");

report.processComplete();
template.close();
reportStream.close();

The output HTML references the image at the relative "images" location, and the image is saved with the specified prefix and an appended identifier:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en">
<style type="text/css">
p {
font-family:Calibri;
font-size:11.0pt;
color:#000000;
margin-top:0.0pt;
margin-bottom:8.0pt;
line-height:1.08;
margin-right:0.0pt;
border:0 none;
text-align:left;
text-indent:0.0pt;
}
IMG.centered{
    display: block;
    margin-left: auto;
    margin-right: auto
}IMG.right{
    float:right;
}IMG.left{
    float:left;
}
#container {
    width:624px;
    margin:0px auto;
}
</style>
</head>
<body><div id="container">
<p><br><img src="images/outputImage1724012377056703473.jpg" width="1024" height="768" /><br></p>
</div></body>
</html>